.\" $Id: PAPI_create_eventset.3,v 1.13 2004/09/28 18:05:16 london Exp $
.TH PAPI_create_eventset 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_create_eventset \- create an EventSet 

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "PAPI_create_eventset (int *" EventSet ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_create_eventset(C_INT\  EventSet,\  C_INT\  check )
.fi

.SH DESCRIPTION
.B "PAPI_create_eventset()"
creates a new EventSet pointed to by 
.I "EventSet,"
which must be initialized to 
.I "PAPI_NULL"
before calling this routine. The user may then add hardware events 
to the event set by calling
.BR "PAPI_add_event" (3) 
or similar routines. 

.SH ARGUMENTS
.I EventSet
-- Address of an integer location to store the new EventSet handle

.SH RETURN VALUES
 On success, this function returns
.B "PAPI_OK."
 On error, a non-zero error code is returned.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
The argument
.I handle
has not been initialized to 
.I PAPI_NULL
or the argument is a NULL pointer.
.TP
.B "PAPI_ENOMEM"
Insufficient memory to complete the operation.

.SH EXAMPLES
.LP
.nf
.if t .ft CW
  int EventSet = PAPI_NULL;

  if (PAPI_create_eventset(&EventSet) != PAPI_OK)
    handle_error(1);

  /* Add Total Instructions Executed to our EventSet */

  if (PAPI_add_event(EventSet, PAPI_TOT_INS) != PAPI_OK)
    handle_error(1);
.if t .ft P
.fi

.SH BUGS
This function has no known bugs.

.SH SEE ALSO
.BR PAPI_destroy_eventset "(3), " PAPI_cleanup_eventset "(3), "  
.BR PAPI_add_event "(3) " 
